﻿Ultra Tools Wildcard Browser 메뉴얼
=============================

1. 개요
-------
Ultra Tools Wildcard Browser는 ComfyUI에서 와일드카드 폴더를 단계적으로 탐색하고,
선택한 와일드카드 파일의 호출문을 다음 형식으로 복사하는 보조 노드입니다.

__폴더/파일__

예:
__01_Natural/K-Pop/female_singer__
__02_Danbooru/SFW/girl/character_name__

이 노드를 제작한 직접적인 이유는 Impact Pack의 `와일드카드 처리기 (Impact)` 노드에서
하단의 `추가할 와일드카드` 목록이 나타나지 않거나, 목록이 표시되어도 항목을 클릭했을 때
와일드카드 이름이 노드 입력란에 삽입되지 않는 환경이 있기 때문입니다.

Ultra Tools Wildcard Browser는 Impact Pack 자체를 수정하는 노드가 아니라, 해당 목록 선택 오류를
쉽게 우회하기 위한 독립적인 탐색·복사 도구입니다. 실제 와일드카드 폴더와 파일 목록을
직접 확인한 뒤 원하는 호출문을 복사하여 `와일드카드 처리기 (Impact)`의 입력란에
붙여넣을 수 있습니다. Impact 노드의 목록이 정상적으로 작동하는 환경에서도, 복잡한
와일드카드 폴더를 단계별로 살펴보고 정확한 경로를 확인하는 용도로 사용할 수 있습니다.

이 노드는 와일드카드 파일의 내용을 펼쳐 보여주는 노드가 아닙니다.
폴더 구조를 찾아가며 사용할 와일드카드 호출문을 빠르게 복사하는 용도입니다.
또한 이미지 생성 출력 노드가 아니므로, 와일드카드 드라이브가 분리되거나
폴더가 사라져도 다른 이미지 생성 작업을 실패시키지 않습니다.


2. 설치 방법
------------
1) ZIP 압축을 풉니다.
2) 압축을 푼 폴더 전체를 ComfyUI의 custom_nodes 폴더 안에 넣습니다.

권장 설치 위치:

ComfyUI/
└─ custom_nodes/
   └─ comfyui-Ultra-Tools/

이 노드와 직접 관련된 주요 파일은 다음과 같습니다.
- wildcard_browser.py
- web/wildcard_browser.js
- 메뉴얼/Ultra Tools Wildcard Browser 메뉴얼.txt

통합 패키지에는 다른 Ultra Tools 노드 파일도 함께 들어 있습니다.

3) ComfyUI를 완전히 종료한 뒤 다시 실행합니다.
4) 브라우저에서 ComfyUI 화면을 새로고침합니다.
5) 이전 JavaScript가 남아 있으면 Ctrl+F5 또는 Ctrl+Shift+R로 강력 새로고침합니다.


3. 노드 추가
------------
ComfyUI 캔버스에서 우클릭 또는 더블클릭한 뒤 다음 위치에서 추가합니다.

Ultra Tools → Ultra Tools Wildcard Browser


4. 기본 폴더 구조
----------------
wildcards_path에는 여러 와일드카드 묶음이 들어 있는 최상위 루트 폴더를 지정합니다.

예:

F:\models\wildcards
├─ 01_Natural
│  ├─ K-Pop
│  │  ├─ female_singer.txt
│  │  └─ male_singer.txt
│  └─ start_K-Pop.txt
├─ 02_Danbooru
│  ├─ SFW
│  │  ├─ boy
│  │  └─ girl
│  └─ NSFW
└─ common_style.txt

folder 드롭다운에는 루트 자체를 뜻하는 [Root]와
루트 바로 아래의 1단계 폴더만 표시됩니다.

[Root]
01_Natural
02_Danbooru

더 깊은 폴더는 드롭다운에 한꺼번에 펼쳐지지 않습니다.
아래 목록에서 폴더를 클릭해 단계적으로 이동합니다.


5. 각 항목의 역할
-----------------

wildcards_path
~~~~~~~~~~~~~~
와일드카드 루트 폴더의 실제 경로입니다.

기본값:
F:\models\wildcards

다른 위치를 사용한다면 실제 환경에 맞는 경로를 입력합니다.
절대 경로뿐 아니라 ComfyUI 실행 위치를 기준으로 한 상대 경로도 사용할 수 있습니다.
경로 변경 후 Enter를 누르거나 입력칸 밖을 클릭하면 목록이 갱신됩니다.

folder
~~~~~~
[Root] 또는 루트 바로 아래의 1단계 폴더를 선택하는 시작점 드롭다운입니다.

[Root]는 wildcards_path에 지정한 루트 폴더 자체를 의미합니다.
루트에 직접 저장된 와일드카드 파일을 보려면 [Root]를 선택합니다.

실제 루트 폴더 안에 이름이 정확히 [Root] 또는 [최상위]인 폴더가 존재하면,
루트 표시와 구분하기 위해 다음처럼 표시됩니다.

./[Root]
./[최상위]

이 항목들은 실제 폴더이며 정상적으로 들어갈 수 있습니다.
이전 버전의 워크플로에 저장된 [최상위] 값은 루트 선택으로 자동 호환됩니다.

아래 목록
~~~~~~~~~
현재 폴더 바로 아래에 있는 항목만 보여줍니다.

- 📁 폴더: 클릭하면 해당 폴더로 이동
- 📁 .. : 한 단계 위 폴더로 이동
- __폴더/파일__ : 클릭하면 와일드카드 호출문 복사
- 상태 또는 오류 문구: 안내용이며 클릭되지 않음

하위 폴더 안의 모든 파일을 재귀적으로 한꺼번에 펼치지 않습니다.
현재 위치에 폴더만 있으면 폴더만 보이고,
현재 위치에 파일이 있으면 그 폴더에 직접 들어 있는 파일만 보입니다.


6. 사용 방법
------------
1) wildcards_path에 와일드카드 루트 경로를 입력합니다.
2) 루트 자체를 보려면 folder에서 [Root]를 선택합니다.
3) 특정 묶음으로 시작하려면 01_Natural, 02_Danbooru 같은 1단계 폴더를 선택합니다.
4) 아래 목록에서 원하는 하위 폴더를 클릭합니다.
5) 다시 하위 폴더가 보이면 같은 방법으로 계속 들어갑니다.
6) 와일드카드 파일 항목을 클릭합니다.
7) 복사된 호출문을 와일드카드를 지원하는 프롬프트 입력 위치에 붙여넣습니다.

Impact Pack의 `와일드카드 처리기 (Impact)`와 함께 사용할 때:

- 하단의 `추가할 와일드카드` 목록이 비어 있거나 클릭 삽입이 작동하지 않아도 됩니다.
- Ultra Tools Wildcard Browser에서 원하는 파일을 찾아 클릭합니다.
- 복사된 `__폴더/파일__` 호출문을 `와일드카드 처리기 (Impact)`의 텍스트 입력란에서
  원하는 위치에 직접 붙여넣습니다.
- 이 방식은 Impact 노드의 목록 UI만 우회하며, 실제 와일드카드 처리 기능은 그대로 사용합니다.

예:

folder에서 02_Danbooru 선택
→ SFW 클릭
→ girl 클릭
→ character_name 클릭
→ 다음 문자열이 복사됨

__02_Danbooru/SFW/girl/character_name__


7. 폴더 이동 규칙
-----------------
- 현재 폴더의 바로 아래 폴더와 파일만 표시됩니다.
- 폴더를 클릭하면 해당 폴더 안으로 이동합니다.
- 루트가 아닌 위치에서는 📁 .. 항목이 표시됩니다.
- 📁 ..를 클릭하면 한 단계 위로 이동합니다.
- 루트 바로 아래 폴더에서 📁 ..를 클릭하면 [Root]로 돌아갑니다.
- 저장한 워크플로를 다시 열면 깊은 하위 폴더 위치도 가능한 한 유지됩니다.
- 현재 폴더가 외부에서 삭제되거나 일시적으로 읽히지 않아도,
  가능한 경우 📁 ..가 남아 있어 상위 폴더로 빠져나올 수 있습니다.
- 경로 또는 폴더를 빠르게 연속 변경해도 늦게 도착한 이전 응답은 무시됩니다.


8. 파일 표시 규칙
-----------------
다음 확장자의 파일만 와일드카드 파일로 표시합니다.

.txt
.yaml
.yml
.json

대소문자는 구분하지 않습니다.
desktop.ini, .DS_Store, 이미지, Python 스크립트 등은 표시하지 않습니다.

복사 문자열에서는 확장자를 제거합니다.

루트의 common_style.txt
→ __common_style__

01_Natural/K-Pop/singer.txt
→ __01_Natural/K-Pop/singer__

같은 폴더에 다음처럼 확장자만 다른 같은 이름의 파일이 여러 개 있으면
와일드카드 호출문이 동일하므로 한 항목만 표시합니다.

sample.txt
sample.yaml
sample.yml
sample.json

선택 우선순위:
.txt → .yaml → .yml → .json

목록 정렬 순서:
1) 폴더
2) 파일

같은 종류 안에서는 이름순으로 정렬됩니다.

브라우저와 서버가 지나치게 큰 목록으로 느려지는 것을 막기 위해
루트의 folder 드롭다운은 최대 5,000개의 폴더를 표시하고,
일반 폴더 목록에서는 최대 10,000개의 표시 항목을 보여줍니다.
또한 지원하지 않는 파일까지 포함해 최대 50,000개의 디렉터리 항목을 검사합니다.
일반 폴더 제한에 도달하면 목록 마지막에 "목록 제한" 안내가 표시됩니다.
루트 드롭다운 제한에 도달하면 화면 상단에 주의 팝업이 표시됩니다.
이 경우 와일드카드 파일을 여러 하위 폴더로 나누어 정리하는 것을 권장합니다.


9. 심볼릭 링크와 정션
---------------------
루트 아래의 심볼릭 링크 또는 Windows 정션이 다른 드라이브의 폴더를 가리켜도
정상적으로 탐색할 수 있습니다.

예:
F:\models\wildcards\MyPack
→ 실제 대상 D:\WildcardPacks\MyPack

단, 자기 자신이나 상위 폴더로 다시 돌아가는 순환 링크는 무한 탐색을 막기 위해
열리지 않습니다. 목록에는 다음처럼 표시될 수 있습니다.

📁 loop [순환 링크]

이 항목은 안내용이며 클릭되지 않습니다.
탐색 경로는 최대 64단계로 제한됩니다.


10. 저장과 워크플로 복원
------------------------
- wildcards_path와 현재 folder 위치는 워크플로에 저장됩니다.
- 아래 파일 목록은 실제 폴더에서 다시 만들 수 있는 표시 데이터이므로
  저장 직전에 해당 위젯 값만 빈 문자열로 바꾸어 워크플로 JSON에 긴 목록을 저장하지 않습니다.
  위젯 위치 자체는 유지하므로 이전 워크플로와의 호환성도 보존됩니다.
- 워크플로를 다시 열면 폴더 목록과 파일 목록을 자동으로 새로 읽습니다.
- 저장 데이터에는 스키마 버전을 함께 기록하며, 현재 형식의 상대 경로나
  Loading/No files 등으로 시작하는 실제 폴더명을 구버전 데이터로 오인하지 않습니다.
- 이전 버전의 두 위젯 구조로 저장된 워크플로도 경로와 폴더 값을 가능한 한 복구합니다.
- 저장한 하위 폴더가 삭제된 경우 오류를 보여주고 상위 이동 경로를 제공합니다.


11. 올바른 동작 예시
--------------------
폴더 구조:

02_Danbooru
├─ NSFW
└─ SFW
   ├─ boy
   └─ girl

folder에서 02_Danbooru를 선택하면 아래 목록에는 다음 두 폴더만 보여야 합니다.

📁 NSFW
📁 SFW

이 단계에서 NSFW와 SFW 안의 모든 파일이 한꺼번에 표시되면 정상 동작이 아닙니다.
SFW를 클릭하면 boy와 girl만 표시되고,
girl을 클릭한 뒤에야 girl 폴더 안의 와일드카드 파일이 표시됩니다.


12. 문제 해결
-------------

노드가 메뉴에 나타나지 않는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 설치 폴더가 ComfyUI/custom_nodes 아래에 있는지 확인합니다.
- ZIP이 한 단계 더 중첩된 구조로 풀리지 않았는지 확인합니다.
- ComfyUI 터미널에 Python 오류가 있는지 확인합니다.
- ComfyUI를 완전히 종료하고 다시 실행합니다.

folder 목록이 갱신되지 않는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- wildcards_path가 실제 존재하는 폴더인지 확인합니다.
- 경로 입력 후 Enter를 누르거나 입력칸 밖을 클릭합니다.
- 외장 또는 네트워크 드라이브가 연결되어 있는지 확인합니다.
- Ctrl+F5 또는 Ctrl+Shift+R로 브라우저를 강력 새로고침합니다.

Error: Wildcards folder not found가 표시되는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 경로 철자와 드라이브 문자를 확인합니다.
- 예: F:\models\wildcards
- 불필요한 따옴표나 오타가 없는지 확인합니다.
- 네트워크 또는 외장 드라이브라면 ComfyUI 실행 계정에서 접근 가능한지 확인합니다.

No files or folders found가 표시되는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
현재 선택한 폴더 안에 직접 들어 있는 지원 폴더나 파일이 없다는 뜻입니다.
지원 확장자와 실제 폴더 위치를 확인합니다.

폴더를 클릭해도 이동하지 않는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 순환 링크로 표시된 폴더는 안전상 열리지 않습니다.
- 이전 JavaScript가 브라우저 캐시에 남아 있을 수 있습니다.
- ComfyUI를 재시작한 뒤 Ctrl+F5 또는 Ctrl+Shift+R을 실행합니다.

파일 클릭 후 복사가 되지 않는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 브라우저의 클립보드 권한을 확인합니다.
- 최신 클립보드 API가 차단되면 기존 브라우저 복사 방식도 자동으로 시도합니다.
- 두 방식이 모두 실패하면 클릭 위치 근처에 복사 실패 안내가 표시됩니다.

워크플로 실행과 무관한 와일드카드 오류가 보이는 경우
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
이 노드는 이미지 생성 출력 노드가 아니므로 정상적으로는 큐 실행에 참여하지 않습니다.
노드의 목록 오류는 와일드카드 탐색 화면에만 표시되며 이미지 생성은 계속할 수 있습니다.


13. 보안 및 네트워크 사용 주의
------------------------------
wildcards_path는 ComfyUI가 실행되는 컴퓨터의 폴더를 읽는 기능입니다.
ComfyUI 서버를 인터넷이나 신뢰할 수 없는 네트워크에 공개하면,
접속 권한을 가진 사용자가 서버의 폴더 이름을 탐색할 가능성이 있습니다.
ComfyUI는 로컬 또는 신뢰할 수 있는 네트워크에서 사용하고,
외부 공개 시에는 인증과 접근 제한을 적용하십시오.


14. 참고 사항
-------------
- 이 노드는 출력 연결이 없는 탐색·복사 보조 노드입니다.
- Show Text 같은 별도 표시 노드는 필요하지 않습니다.
- folder 드롭다운은 [Root]와 루트 바로 아래 폴더만 보여주는 것이 정상입니다.
- 더 깊은 하위 폴더는 아래 목록에서 클릭해 탐색합니다.
- 대형 폴더나 느린 외장·네트워크 드라이브의 파일 탐색은 전용 백그라운드 작업 풀에서
  최대 2개까지만 동시에 처리됩니다. 대기 중 취소된 요청은 디스크 작업으로 제출하지 않아
  작업 대기열이 불필요하게 쌓이지 않습니다. 이미 시작된 운영체제 파일 읽기는 즉시
  중단할 수 없지만, 완료될 때까지 실행 슬롯을 유지해 실제 동시 작업 수를 제한합니다.
- 내부 API 요청은 ComfyUI의 표준 api.fetchApi 경로를 사용하므로 리버스 프록시의
  하위 경로와 사용자·인증 헤더 설정을 따릅니다.
